package com.xyzwps.orm.repository;

import com.xyzwps.orm.model.Tag;
import com.xyzwps.orm.exception.*;

import java.util.List;
import java.util.Optional;

/**
 * Javadoc 中所说的 tagName 是否存在，是指 tagName <em>相对于指定用户</em>是否存在。
 * 图方便，doc 中把<em>相对于指定用户</em>这个前提省略。在读下面的 doc 时，请自明。
 */
public interface TagRepository {
    /**
     * 插入一个新 tag。
     * <p>
     * 如果 tagName 已存在于数据库中，则抛出 {@link TagDuplicateException}
     *
     * @param tag 忽略 tagId
     * @return 自增 tagId
     */
    int insert(Tag tag);

    /**
     * 更新 tag
     * <ul>
     *  <li>如果被更新的 tag 不存在于数据库中，不必抛出异常。</li>
     *  <li>如果 tagName 已存在于数据库中，则抛出 {@link TagDuplicateException}</li>
     * </ul>
     *
     * @param tag 被更新的 tag。要求 {@code tagId != null}
     */
    void update(Tag tag);

    /**
     * 按 tagId 删除指定 tag
     *
     * @param tagId tagId
     */
    void delete(int tagId);

    /**
     * 按 tagId 查询 tag
     */
    Optional<Tag> selectByTagId(int tagId);

    /**
     * 查询用户的所有 tag。结果按 tagId 递增。
     * <p>
     * 如果没有 tag，则返回 empty list
     */
    List<Tag> selectAllForUser(int userId);
}
